Parent | Child | Previous | Next
 

TransForm QuickLink

Description

Create URLs that point users directly to a specific form.

Overview

Many types of workflow involve sending a message to an individual to have them click on a link and automatically view a single form, often answering questions such as giving approval, and then submitting that form for further action. The TransForm QuickLink functionality provides this capability.

Other parts of TransForm, like the Filler and Management Console, require the user to run them and then locate or create an appropriate form instance and work with it along with a list of other form instances and types of forms. This general purpose operation does not easily fit into those link-driven types of workflows and is cumbersome in those cases.

QuickLink also makes it easy to send a link to a user that includes custom data to pre-populate parts of a form before editing. For example, an email created from a template can include template data fields in the URL which are in turn passed to the form.

Another example of using QuickLink is an intranet web page that uses simple Javascript to create a URL that any authorized user can click on, log in with their credentials (if they are not already logged in), and have a new form instance created using custom initialization data (such as a work order number). The user can then fill in the rest of the form and then submit it – all in just a few clicks.

QuickLink may also be used loaded into an <IFRAME> in another web application. The other application can use this framed QuickLink to view and edit form instances in a coordinated way. Instructions about this use along with code samples are in another document.

Properties of QuickLink

Using QuickLink to view and edit a form instance is similar to using the TransForm Filler once a particular form instance is chosen. Only the Form Details screens and Editors are shown. Unlike the Web Filler, there is no Forms List with QuickLink nor an Add a Blank Form list.

Unlike the Mobile Filler but similar to the Web Filler, QuickLink runs in a browser connected to the Internet. It is launched by going to a custom URL, usually from an email, text message, QR code, or web page. Once launched, it supports the viewing, editing, and saving of a single form instance. The link includes special information to identify the desired form instance. Optionally, the link can specify initial automatic positioning of the view of the form to a specific field or section.

QuickLink, once invoked, requires login with user name, password, and account credentials which persist in the browser during subsequent sessions. Multiple tabs in a browser may be open at once, all running different QuickLink URLs to edit different form instances.

Once a form instance has been displayed for viewing and/or edit, the user may quit the tab without saving. Once edits have been made, a “Save” button will be enabled in the upper left above the form. Pressing that button, or pressing a form button that executes a “save” operation, will upload the form instance data and switch to a final screen.

Four Modes of Operation Available

TransForm QuickLink works in one of four modes of operation specified in the URL: Edit a single explicit existing form instance, Edit a duplicate of an explicit existing form instance, Create and edit a new form instance of a specified form type, and Choose a form instance by viewing one or more TransForm Queues for the account and selecting one of the available form instances in the queue.

The URL that is used to invoke QuickLink must include parameters (often called a Query component of the URL) after the domain and path, separated by a “?” character. The structure of the query follows a common Internet syntax. For example, the URL could be:

http://transform.alphasoftware.com/QuickLink?m=d&f=lflza6l9_br9pnc11

In this case, the "http://transform.alphasoftware.com/QuickLink" is the part that indicates the address on a particular server. We will call that the "QuickLink Web Address". The part after the "?", "m=d&f=lflza6l9_br9pnc11", is the query. Multiple parameters in the query are separated by the "&” character. An initial "&" after the "?" is optional. (The construction of URLs with query strings this way is a normal, well-documented, web-development technology.)

The four QuickLink modes are specified by using the parameters in the query. The "m" parameter is used to explicitly specify the mode. Allowed values are: i, d, n, and q (representing Instance, Duplicate, New, and Queue). If the m parameter is missing, “i” is assumed.

The other parameters are used to provide the details. The "f" parameter specifies a form instance ID. This is one of the metadata fields for a form instance and uniquely identifies the form instance within the TransForm system. The “a” parameter specifies the Account ID for the account that the user must be logged into. The “q” parameter specifies a specific Queue ID within the account. The “d” parameter specifies the Form Definition ID of a form type for the account. The “v” parameter specifies a URI-encoded string to be passed to the form instance being edited as the TPL $environment.editformvalue System Data value. The “t” parameter specifies a location other than the default top of the form being displayed to initially position to be visible on the screen.

The ”ro” parameter, if present with “m=i” or “m=im”, displays the form instance as a “read-only” form. The form may be viewed, but changes may not be made, action buttons will not be executed, and saving will be disabled.

The four modes and the other parameters are explained in more detail below.

Edit explicit form instance

The Instance Mode is used to bring up an explicit, existing form instance for viewing and for optional editing and updating. The forms of the URL are any of ("QuickLink" should be the QuickLink Web Address, such as transform.alphasoftware.com/quicklink):

QuickLink?m=i&f=formInstanceID

QuickLink?f=formInstanceID

QuickLink?formInstanceID

In the last case, a parameter with no value that looks like a formInstanceID is treated the same as an "f" parameter.

Edit explicit form instance with Management Console role

The Instance with Management Console Role Mode is used to bring up an explicit, existing form instance for viewing and for optional editing and updating. Unlike the plain Edit Explicit Instance mode, the logged in user is evaluated for permissions as a Management Console user for the account of the existing form instance. The user need not be the person to whom the form is assigned, if any. The forms of the URL are any of (“QuickLink” should be the QuickLink Web Address, such as transform.alphasoftware.com/quicklink):

QuickLink?m=im&f=formInstanceID

QuickLink?formInstanceID&m=im

QuickLink?m=im&f=formInstanceID&ro

In the second case, a parameter with no value that looks like a formInstanceID is treated the same as an “f” parameter. In the third case, the form instance will be shown in a read-only state, and saving will be disabled.

Edit duplicate of an explicit form instance

The Duplicate mode downloads an explicit, existing form instance, makes a copy, and then brings that copy up for editing as a new form instance with a new Form Instance ID. (The logged in user must have permission to access the original form instance for edit.)

QuickLink?m=d&f=formInstanceID

This is useful, for example, to be able to always start from a particular partially filled-out form by just clicking a link.

Edit form chosen from a queue

The Queue mode brings up the Claim Forms screen that is used to display the account’s queues and claim a form there to assign to the user and start editing.

QuickLink?m=q&a=accountID&q=optionalQueueName

If the optional "q=optionalQueueName" parameter is present, that queue will be shown directly. If not present, then the list of queues for that user will be displayed, like with the Claim Forms menu item in the Filler.

When a form instance in a queue is selected, and then the button is pressed to submit a claim for that form, and the claim is accepted, then the form will be removed from the queue, be assigned to the logged in user, and then brought up for edit.

Create and edit new form instance

The New Instance mode creates a new, blank form instance for the specified form type. This is similar to tapping the "+ Add Blank Form" button in the Filler, and then selecting that form type.

QuickLink?m=n&a=accountID&d=formDefinitionID

The "t" parameter

For all of the modes, when a form instance is brought up for edit, the initial position may be specified with the "t" parameter. This is similar to having tapped a Go To command’s button on the form to bring a particular part of the form into view. It may be used, for example, to position the screen at a signature field for sign off, or to a place in a data group to add a new observation.

There are two types of values:

&t=targetname

&t=qID

The "targetname" is the same target name that would be used by a Go To command in a form type definition. The first Define Target command encountered in the form with that name will be used.

The "qID" is a special value that uniquely defines a particular command in a rendered form. This can be top level or even a specific field within a specific data group item. It has a command-line part and an optional path part.

The command-line part consists of a number that corresponds to the 0-origined position of the command in the Form Commands shown in the Designer. (For example, the first would be 0, the second would be 1.) The Designer displays line numbers that are 1-origined, so that number minus one would be used. This is then followed by a "_" character to finish the command-line part. For example, the third command line would be "2_".

The optional path part consists of the path of Data Group array name and 0-origined index combinations to get to that particular command. (The same command may be used repeatedly to define the display of fields for each item in a Data Group’s array of field values.) For example, a Data Group with an array name of "photos", and a "phototype" value within the Data Group, could have a qID of "15_photos,2," to specify the third item in the Data Group. Data Groups within Data Groups would have additional elements in the path, e.g., "16_photos,2,people,0,".

The "v" parameter

The "v" parameter specifies a URI-encoded string to be passed to the form instance being edited as the TPL $environment.editformvalue System Data value. For example, it could be used to pass a single value or a comma-separated list of multiple values.

This parameter (URI-encoding of "A & B Market"):

&v= A%20%26%20B%20Market

Could be used by this TPL code:

ON *LOAD

IF $environment.editform

#storename = $environment.editformvalue

ENDIF

ENDON

The field "storename" would show "A & B Market."

Other System Data Value

$environment.editform is true ("1" instead of "") when running as QuickLink. This can be used to permit a form to behave differently depending upon whether it is in the plain Filler or QuickLink, as used in the example above

Built-in functions helpful for QuickLink

To enable a Button and other uses of TPL to trigger the saving of the form instance data to the server, there is the following function in the Filler (and in QuickLink):

changeStateAndSave(newstatus)

changeStateAndSave(newstatus,noFiller)

The "newstatus" must be a Status ID (not the Display text) to set for the form instance. For example: "open" or "submitted". To leave it unchanged, the $#status Metadata value may be used as an argument.

The "noFiller" value, if present, sets the form instance’s nofiller metadata value. If true, nofiller will be set to "Y" which will prevent the form instance, once saved, from being downloaded to the Filler or QuickLink in the future.

Once successfully executed, the form instance will be saved back to the server. Like a Change Status button, and back-arrow button above the Form Details in the Filler, the *FINISHED event is triggered. If running in the Filler, then all modified form instances will be saved. (In QuickLink there is only a single form instance to be saved.)

In QuickLink, in the upper-left corner of the window when viewing the top-level page, there is a "Save" button. If the form has not been modified, the button will be disabled. In order to only allow saving through programmatic means, such as a button with TPL and the changeStateAndSave() function or an IF command conditionally showing a Change Status button, the Save button may be hidden programmatically with a function. It takes true ("1") or false ("") as an argument.

editFormHideDone(hideIfTrue)